[v9] refactor!: instance descriptors, dynamically map ThreeElements #2465

CodyJasonBennett · 2022-08-27T16:29:23Z

Continues #2378, dropping architecture changes. Fixes #2250.

Instance Descriptors

This PR creates instance descriptors to separate instance representations from their underlying objects. With them separated, we can avoid mutating objects with flags like dispose={null} and efficiently swap objects at runtime (e.g. in switchInstance). This allows the internal lifecycle of instances to change without breaking user code -- we still create objects in createInstance but could defer that to handleContainerEffects if needed. Instances are an implementation detail of the reconciler, with elements' refs pointed to instance.object.

react-three-fiber/packages/fiber/src/core/renderer.ts

Lines 33 to 45 in ee6bf62

    
           export interface Instance<O = any> { 
        
             root: UseBoundStore<RootState> 
        
             type: string 
        
             parent: Instance | null 
        
             children: Instance[] 
        
             props: InstanceProps<O> & Record<string, unknown> 
        
             object: O & { __r3f?: Instance<O> } 
        
             eventCount: number 
        
             handlers: Partial<EventHandlers> 
        
             attach?: AttachType<O> 
        
             previousAttach?: any 
        
             isHidden: boolean 
        
           }

Notably, objects is renamed children and is used for all instances whereas previously it only contained attached children. Furthermore, memoizedProps is renamed props and indiscriminately contains elements' props.

Dynamically mapped ThreeElements

Additionally, three.js types for JSX.IntrinsicElements are no longer hard-coded and dynamically mapped to ThreeElements. This can let us relax the three peer dep significantly and make proper use of semver with types with the most recent feature we use being THREE.ColorManagement of r139 and ambient @types/webxr of r141. Consequently, the ReactThreeFiber type namespace is removed with elements' props being defined within ThreeElements.

react-three-fiber/packages/fiber/src/three-types.ts

Lines 1 to 61 in ee6bf62

    
           import type * as THREE from 'three' 
        
           import type { EventHandlers } from './core/events' 
        
           import type { InstanceProps, ConstructorRepresentation } from './core/renderer' 
        
           type Mutable<P> = { [K in keyof P]: P[K] | Readonly<P[K]> } 
        
           type NonFunctionKeys<P> = { [K in keyof P]-?: P[K] extends Function ? never : K }[keyof P] 
        
           type Overwrite<P, O> = Omit<P, NonFunctionKeys<O>> & O 
        
           interface MathRepresentation { 
        
             set(...args: any[]): any 
        
           } 
        
           interface VectorRepresentation extends MathRepresentation { 
        
             setScalar(s: number): any 
        
           } 
        
           type MathProps<P> = { 
        
             [K in keyof P]: P[K] extends infer M 
        
               ? M extends THREE.Color 
        
                 ? ConstructorParameters<typeof THREE.Color> | THREE.ColorRepresentation 
        
                 : M extends MathRepresentation 
        
                 ? M extends VectorRepresentation 
        
                   ? M | Parameters<M['set']> | Parameters<M['setScalar']>[0] 
        
                   : M | Parameters<M['set']> 
        
                 : {} 
        
               : {} 
        
           } 
        
           interface RaycastableRepresentation { 
        
             raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void 
        
           } 
        
           type EventProps<P> = P extends RaycastableRepresentation ? Partial<EventHandlers> : {} 
        
           interface ReactProps<P> { 
        
             children?: React.ReactNode 
        
             ref?: React.Ref<P> 
        
             key?: React.Key 
        
           } 
        
           type ElementProps<T extends ConstructorRepresentation, P = InstanceType<T>> = Partial< 
        
             Overwrite<P, ReactProps<P> & MathProps<P> & EventProps<P>> 
        
           > 
        
           export type ThreeElement<T extends ConstructorRepresentation> = Mutable< 
        
             Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>>, 'object'>> 
        
           > 
        
           type ThreeExports = typeof THREE 
        
           type ThreeElementsImpl = { 
        
             [K in keyof ThreeExports as Uncapitalize<K>]: ThreeExports[K] extends ConstructorRepresentation 
        
               ? ThreeElement<ThreeExports[K]> 
        
               : never 
        
           } 
        
           export interface ThreeElements extends ThreeElementsImpl { 
        
             primitive: Omit<ThreeElement<any>, 'args'> & { object: object } 
        
           } 
        
           declare global { 
        
             namespace JSX { 
        
               interface IntrinsicElements extends ThreeElements {} 
        
             } 
        
           }

Unified ThreeElement interface

When using extend, the Object3DNode, BufferGeometryNode, MaterialNode, LightNode, and Node interfaces are unified to just ThreeElement<typeof CustomElement>. ThreeElement does not care about the element type, but will map properties based on their signature which best represents the behavior of applyProps.

import { type ThreeElement, extend } from '@react-three/fiber'

declare module '@react-three/fiber' {
  interface ThreeElements {
    customElement: ThreeElement<typeof CustomElement>
  }
}

extend({ CustomElement })

Stable container-effects

Moves attach and interactivity to handleContainerEffects which will fire when trees are linked and finalized. This ensures that effects are not duplicated due to suspense and complete outside of commit, so we're never late and present an incomplete tree. Detailed in #2483.

Internal Stability

As a follow-up to #2491, I've added coverage for utils and the reconciler lifecycle. This is basically a rewrite of renderer tests to fully cover the basics and ensure they work in difficult situations we've designed around.

codesandbox-ci · 2022-08-27T16:29:45Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit ee6bf62:

Sandbox	Source
example	Configuration
append-bug	Issue #2250

packages/fiber/src/index.tsx

packages/fiber/src/three-types.ts

…onciler cases

CodyJasonBennett · 2022-09-13T09:27:47Z

@joshuaellis, I'm not very clear on some of the semantics of RTTR's API. getInstance would return the nearest class component or host component (native element), but not function components. Would you prefer to look the Fiber up by the element passed to create and return its instance if possible (or null)? I'd like to improve type safety and predictability in this area.

joshuaellis · 2022-09-13T11:40:03Z

@CodyJasonBennett it's largely modelled of react-test-renderer which explicitly discusses the absence of functional components because they don't have an instance. Do you see a benefit in your approach? I'm not sure how much it's used?

CodyJasonBennett · 2022-09-13T11:45:08Z

To clarify, I mean to do Fiber traversal based on the literal JSX passed to create. So, a function component would return null for getInstance and we can type it accordingly.

I wanted to clarify the intent behind class components since it was not clear whether getInstance referred to host components (native elements) or any component with instance state (this would also include portals). I would prefer to type native elements as Instance here, in any case, similar to useInstanceHandle.

joshuaellis · 2022-09-13T12:08:41Z

I wanted to clarify the intent behind class components since it was not clear whether getInstance referred to host components (native elements)

I agree, I don't think portals would be included. I don't believe they are in rtr.

To clarify, I mean to do Fiber traversal based on the literal JSX passed to create. So, a function component would return null for getInstance and we can type it accordingly.

Sounds good to me!

CodyJasonBennett · 2022-09-15T11:27:13Z

@joshuaellis, @drcmda, @gsimone, @krispya, any objections or withstanding issues before merging? Changes are mostly internal, but I've documented the implications and added test coverage for all the moving parts. I would break this up into another PR, but I didn't want to wait on coverage.

r3f refactored their internal typings of Instance during pmndrs/react-three-fiber#2465 - before: Instance represented a THREE-object with additional parameters: __r3f: LocalState, children, remove, add and raycast - now: Instance: LocalState with additional parameter: object, props and children - object: is the THREE-object with additional parameter __r3f ( = a circular reference back to this Instance) - props contains the props of the component, without children and ref - children contain all the children of the component (before children only contained the attached children)

refactor: use instance descriptors

40d36bb

CodyJasonBennett mentioned this pull request Aug 27, 2022

[v9] experiment: rework reconciler architecture, create objects on commit #2378

Closed

CodyJasonBennett changed the title ~~refactor: use instance descriptors~~ [v9] refactor: use instance descriptors Aug 27, 2022

CodyJasonBennett added 5 commits August 27, 2022 17:37

fix: remove duplicate args check, align text warning

5923e1f

fix: don't overwrite containers in prepare

816d231

fix: type applyProps, flatten reconciler

cd36cfb

fix: don't recursively remove on swap

0fdf940

refactor(types): automate ThreeElements

dc4e3b1

CodyJasonBennett force-pushed the refactor/instance-descriptors branch from 8632cdf to dc4e3b1 Compare August 28, 2022 19:05

CodyJasonBennett commented Aug 28, 2022

View reviewed changes

packages/fiber/src/index.tsx Outdated Show resolved Hide resolved

CodyJasonBennett changed the title ~~[v9] refactor: use instance descriptors~~ [v9] refactor!: instance descriptors, dynamically map ThreeElements, JSX.IntrinsicElements Aug 28, 2022

CodyJasonBennett changed the title ~~[v9] refactor!: instance descriptors, dynamically map ThreeElements, JSX.IntrinsicElements~~ [v9] refactor!: instance descriptors, dynamically map ThreeElements Aug 28, 2022

CodyJasonBennett added 9 commits August 28, 2022 14:57

fix: don't overwrite dispose

16092cf

fix: don't leak react internals into instance props

98d53e2

fix: also exclude primitive props

1a31024

chore: cleanup event types

5799b6b

fix: add back three-types, export ThreeElements as interface

53c24d1

chore(types): cleanup

ab97027

fix: check obj type in dispose, reconstruct with args length

3ef4354

fix(types): move primitive to ThreeElements

a8e9225

chore(types): cleanup helper signatures, require object in primitives

8ffad25

CodyJasonBennett force-pushed the refactor/instance-descriptors branch from d1c1fcc to 8ffad25 Compare August 30, 2022 08:51

CodyJasonBennett added 2 commits August 30, 2022 04:13

chore(docs): update onUpdate, TS sections

02af69a

chore(types): cleanup

903392e

CodyJasonBennett commented Aug 30, 2022

View reviewed changes

packages/fiber/src/three-types.ts Outdated Show resolved Hide resolved

fix(types): ensure instanceprops override nodeprops

cb1c6b9

CodyJasonBennett force-pushed the refactor/instance-descriptors branch from 1104c5b to cb1c6b9 Compare August 31, 2022 05:16

fix(types): don't exclude functions from JSX

90fefb9

CodyJasonBennett mentioned this pull request Aug 31, 2022

[v9?] New API that returns "current parent" #2467

Closed

CodyJasonBennett added 16 commits September 10, 2022 05:08

refactor(applyProps): pick from root obj on HMR

972106c

fix(types): primitive accepts truthy non-literal types

5cb947b

fix(renderer): revalidate args on prop change

eeaebd3

fix(core): don't mutate on swap, de-dup events

556da62

fix(applyProps): handle event handler HMR

d09a5d6

chore(tests): prop diffing & updates, harden reconstruct, isolate rec…

de5c80f

…onciler cases

chore(tests): cleanup

d51a426

chore: cleanup removeChild

78f0c53

fix(applyProps): loosen literal check

23f250d

chore(applyProps): cleanup

e311e86

fix(applyProps): validate scalar type

54319d2

chore(tests): add undefined, layers applyProps cases

870b6db

refactor(utils): move HMR to diffProps

b5081a6

fix(core): replace old instance on reconstruct

817f427

Merge branch 'v9' into refactor/instance-descriptors

a969026

Merge branch 'v9' into refactor/instance-descriptors

ab801cc

Merge branch 'v9' into refactor/instance-descriptors

ee6bf62

CodyJasonBennett merged commit 1e7e0a1 into v9 Sep 18, 2022

CodyJasonBennett deleted the refactor/instance-descriptors branch September 18, 2022 11:44

This was referenced Nov 19, 2022

Custom elements not compatible with React + Typescript aframevr/aframe#4826

Open

[v9] experiment: create objects with container effects #2607

Merged

CodyJasonBennett mentioned this pull request Dec 17, 2022

v9 type export coverage #2668

Closed

CodyJasonBennett mentioned this pull request Jan 21, 2023

fix(core): don't use three.js math identity for HMR #2726

Merged

bigmistqke mentioned this pull request Jul 17, 2023

next solid-three solidjs-community/solid-three#12

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[v9] refactor!: instance descriptors, dynamically map ThreeElements #2465

[v9] refactor!: instance descriptors, dynamically map ThreeElements #2465

CodyJasonBennett commented Aug 27, 2022 •

edited

Loading

codesandbox-ci bot commented Aug 27, 2022 •

edited

Loading

CodyJasonBennett commented Sep 13, 2022 •

edited

Loading

joshuaellis commented Sep 13, 2022

CodyJasonBennett commented Sep 13, 2022 •

edited

Loading

joshuaellis commented Sep 13, 2022

CodyJasonBennett commented Sep 15, 2022

	export interface Instance<O = any> {
	root: UseBoundStore<RootState>
	type: string
	parent: Instance \| null
	children: Instance[]
	props: InstanceProps<O> & Record<string, unknown>
	object: O & { __r3f?: Instance<O> }
	eventCount: number
	handlers: Partial<EventHandlers>
	attach?: AttachType<O>
	previousAttach?: any
	isHidden: boolean
	}

	import type * as THREE from 'three'
	import type { EventHandlers } from './core/events'
	import type { InstanceProps, ConstructorRepresentation } from './core/renderer'

	type Mutable<P> = { [K in keyof P]: P[K] \| Readonly<P[K]> }
	type NonFunctionKeys<P> = { [K in keyof P]-?: P[K] extends Function ? never : K }[keyof P]
	type Overwrite<P, O> = Omit<P, NonFunctionKeys<O>> & O

	interface MathRepresentation {
	set(...args: any[]): any
	}
	interface VectorRepresentation extends MathRepresentation {
	setScalar(s: number): any
	}
	type MathProps<P> = {
	[K in keyof P]: P[K] extends infer M
	? M extends THREE.Color
	? ConstructorParameters<typeof THREE.Color> \| THREE.ColorRepresentation
	: M extends MathRepresentation
	? M extends VectorRepresentation
	? M \| Parameters<M['set']> \| Parameters<M['setScalar']>[0]
	: M \| Parameters<M['set']>
	: {}
	: {}
	}

	interface RaycastableRepresentation {
	raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void
	}
	type EventProps<P> = P extends RaycastableRepresentation ? Partial<EventHandlers> : {}

	interface ReactProps<P> {
	children?: React.ReactNode
	ref?: React.Ref<P>
	key?: React.Key
	}

	type ElementProps<T extends ConstructorRepresentation, P = InstanceType<T>> = Partial<
	Overwrite<P, ReactProps<P> & MathProps<P> & EventProps<P>>
	>

	export type ThreeElement<T extends ConstructorRepresentation> = Mutable<
	Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>>, 'object'>>
	>

	type ThreeExports = typeof THREE
	type ThreeElementsImpl = {
	[K in keyof ThreeExports as Uncapitalize<K>]: ThreeExports[K] extends ConstructorRepresentation
	? ThreeElement<ThreeExports[K]>
	: never
	}

	export interface ThreeElements extends ThreeElementsImpl {
	primitive: Omit<ThreeElement<any>, 'args'> & { object: object }
	}

	declare global {
	namespace JSX {
	interface IntrinsicElements extends ThreeElements {}
	}
	}

[v9] refactor!: instance descriptors, dynamically map ThreeElements #2465

[v9] refactor!: instance descriptors, dynamically map ThreeElements #2465

Conversation

CodyJasonBennett commented Aug 27, 2022 • edited Loading

Instance Descriptors

Dynamically mapped ThreeElements

Unified ThreeElement interface

Stable container-effects

Internal Stability

codesandbox-ci bot commented Aug 27, 2022 • edited Loading

CodyJasonBennett commented Sep 13, 2022 • edited Loading

joshuaellis commented Sep 13, 2022

CodyJasonBennett commented Sep 13, 2022 • edited Loading

joshuaellis commented Sep 13, 2022

CodyJasonBennett commented Sep 15, 2022

CodyJasonBennett commented Aug 27, 2022 •

edited

Loading

codesandbox-ci bot commented Aug 27, 2022 •

edited

Loading

CodyJasonBennett commented Sep 13, 2022 •

edited

Loading

CodyJasonBennett commented Sep 13, 2022 •

edited

Loading